home *** CD-ROM | disk | FTP | other *** search
/ Merciful 1 / Merciful - Disc 1.iso / software / d / devpak / devpakv3.01kickstartv1.3b.dms / devpakv3.01kickstartv1.3b.adf / arp / prodocs / GADS < prev    next >
Text File  |  1991-11-20  |  7KB  |  199 lines
  1.  
  2.  
  3.  
  4.      GADS(33.4)          ARP Programmers Manual        GADS(33.4)
  5.  
  6.  
  7.  
  8.      NAME
  9.       GADS -- Do standard AmigaDOS command line parsing.
  10.  
  11.      SYNOPSIS
  12.       Count    = GADS(    "line",    len, "help"  args, "tplate");
  13.         d0          a0     d0    a1     a2       a3
  14.  
  15.      FUNCTION
  16.       This function    performs the standard AmigaDOS style command
  17.       line parsing,    using the standard AmigaDOS style templates.
  18.       It also handles interactive command lines for    you.
  19.  
  20.       This program will also perform all the normal    AmigaDOS
  21.       processing on    the command line before    the parse.  In
  22.       particular, this means handling any escape characters    that
  23.       are found in the line.  The method used by AmigaDOS (and in
  24.       this function) is to escape quoted commands, but not
  25.       unquoted commands. Quotes will be stripped unless escaped.
  26.  
  27.       Note that ArpLib recognizes a    more extensive escape
  28.       vocabulary than AmigDOS (see EscapeString).  Note also that
  29.       one exception    to the above occurs when a function is passed
  30.       a null 'tplate' pointer.
  31.  
  32.      INPUTS
  33.       "cmdline" -- pointer to the command line, just as you    get it
  34.       from DOS.
  35.  
  36.       cmdlen -- length of command line, just as handed to you by
  37.       DOS.
  38.  
  39.       argarray -- Pointer to the start of an array of longwords
  40.           which    will receive the results of the    argument
  41.           parse. There must be as many longwords in this array
  42.           as there are arguments in the    template. There    must
  43.           ALWAYS be at least one element in this array.
  44.  
  45.       "tplate" -- Pointer to an AmigaDOS style template.  This
  46.           function assumes that    the template is    'well formed',
  47.           i.e.,    no spaces, tabs, etc., and that    it null
  48.           terminated.  Do NOT end your template    with ':'.  It
  49.           may contain mixed cases.
  50.  
  51.       "xtra    help" -- optional extra    help string, which may be as
  52.           long as you like, and    include    any type of characters
  53.           you desire.  The user    will see this string if    they
  54.           type a question mark after they have already entered
  55.           interactive processing.  This    should be NULL if you
  56.           do not have any xtra help to supply.
  57.  
  58.      RESULT
  59.       COUNT    -- The number of arguments found, or -1    if there is an
  60.  
  61.  
  62.  
  63.      Page 1                         (printed 2/22/88)
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.      GADS(33.4)          ARP Programmers Manual        GADS(33.4)
  71.  
  72.  
  73.  
  74.           error    in the comand line.  This function is fairly
  75.           demanding about command line syntax.
  76.  
  77.       ArgArray -- If COUNT is nonzero, ArgArray contains the
  78.           results of the parse.     Each argument (if present)
  79.           will be placed in the    position of the    argument array
  80.           reserved for it in the template.  For    example, in
  81.           the template "DIR,TO", DIR will always appear    in the
  82.           first    argument position, and TO will always appear
  83.           in the second, regardless of how the user supplied
  84.           the string.
  85.  
  86.       If COUNT is zero, then the ArgArray contains the values it
  87.           was initialized with.     This allows you to submit
  88.           preset argument values.
  89.  
  90.       If COUNT is less than    zero, an argument error    occured, and
  91.           the first entry in the ArgArray is a pointer to an
  92.           error    string which describes the error.  Typically,
  93.           a program will display this message and then exit.
  94.  
  95.      ADDITIONAL    CONSIDERATIONS
  96.       This function    will return an error if    the user omitted a
  97.       required argument (indicated by a /A in the template)    only
  98.       if the command line is non-null.
  99.  
  100.       The initial command line pointer may not be valid after a
  101.       call to this function, since GADS() uses the resource
  102.       tracking functions to    allocate additional memory for
  103.       interactive command line processing as needed.
  104.  
  105.       If template is a NULL    pointer, special command line
  106.       processing takes effect.  This option    is used    by programs
  107.       such as Echo or Set which do more of their own command line
  108.       processing, but still    want the Escape    and string cleaning
  109.       functions of GADS() to be in effect.
  110.  
  111.      Additions for V33.4
  112.       Two additions    have been made to GADS() for this release of
  113.       the library.    A new template type, sometimes referred    to as
  114.       multiargs, has been added to the original set    of template
  115.       types    of AmigaDOS.  This allows an essentially infinite
  116.       number of arguments to be supplied, and dispenses with the
  117.       ugly and limited ",,,,,,,,,,," construct.  Note that this is
  118.       still    supported, if you wish to use it.
  119.  
  120.       Multiargs are    indicated by using "/..." as the type
  121.       indicator.  For example, the template    "Files/...,OPT/K",
  122.       allows any number of files to    be entered.  The GADS()    return
  123.       value    will be    the total number of arguments entered, as
  124.       always.  The value of    the multiarged item will be of type
  125.       *(*char[]), i.e., a pointer to an array of character
  126.  
  127.  
  128.  
  129.      Page 2                         (printed 2/22/88)
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.      GADS(33.4)          ARP Programmers Manual        GADS(33.4)
  137.  
  138.  
  139.  
  140.       pointers.  The arguments will    be placed in this array    in the
  141.       order    in which they are found, and the last item is
  142.       guaranteed to    be NULL.  Note that the    memory for this    array
  143.       is allocated by GADS() using the tracking functions, you do
  144.       not have to obtain, and should not free, this    memory.
  145.  
  146.       One important    aspect of using    the multiarg template type in
  147.       designing templates is that you should allow only keywords
  148.       or switches to follow    the multiarged item.  For example:
  149.  
  150.            "Files/...,TO/K,SILENT/S"
  151.  
  152.       would    work well, but the following template has a problem:
  153.  
  154.            "Files/...,TO"
  155.  
  156.       If a user specifies the TO argument without the keyword TO,
  157.       the parsing routine has no way to tell where the Files/...
  158.       args end, and    the TO argument    begins,    therefore, it will
  159.       parse    the TO argument    as a member of the Files/... type.
  160.       This 'swallowing' of optional    arguments can cause
  161.       difficulties,    and should be avoided by using only one
  162.       optional argument, the multiarged one, per template.    If you
  163.       must use additional optional arguments, then these should
  164.       preceed the multiarg argument.
  165.  
  166.       Ordinarily, GADS() (like AmigaDOS) regards the equal sign
  167.       (=) as a statement separator.     You can now override that if
  168.       you wish by using the    character sequence "-="    to begin a
  169.       template. This will not appear to the    user if    he types a
  170.       '?', but it will cause the equal signs to be treated as
  171.       literal characters, rather than delimiters.  This is useful
  172.       in programs like Set.     The lack of this feature in the
  173.       original AmigaDOS arg    parser is probably why Assign has such
  174.       an unnatural syntax.
  175.  
  176.      BUGS
  177.       No error checking is performed on the    actual syntax of the
  178.       template.  This routine assumes you did it right.
  179.  
  180.       Could    alter the original cmdline area, and will, except in
  181.       the case of interactive input.
  182.  
  183.      SEE ALSO
  184.       EscapeString(), ReadLine(), ArpAlloc()
  185.  
  186.      AUTHOR
  187.       SDB
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.      Page 3                         (printed 2/22/88)
  196.  
  197.  
  198.  
  199.